import { Meta, Status, Props, Story } from '../../../../.storybook/components';
import * as Stories from './Headline.stories';

<Meta of={Stories} />

# Headline

<Status variant="stable" />

The Headline component is used for describing the contents of a page or page section. It is an essential part of a page's structure, helping organize information for users.

<Story of={Stories.Base} inline={false} />
<Props />

## Component variations

### Sizes

The Headline component comes in three sizes.

Use the `m` size for card headers and `l` for page titles in web applications. Consider using the [Display](Typography/Display) component for specific use cases such as landing pages.

<Story of={Stories.Sizes} inline={false} />

---

## Accessibility

Headings are a fundamental aspect of creating accessible interfaces. Sighted users rely on them to easily find what they want on a page, while assistive technology allows users to jump between them for easier access to the page's different sections.

### Best practices

#### Each page should have a single `<h1>`

The `<h1>` represents the page title. Pages should all have one (and only one), and it should be similar to the document's `<title>`.

#### Headings should be descriptive

A heading's text should describe its section's content accurately and concisely. Because screen reader users will use them to navigate the page's contents, headings must also make sense out of the content's context, as if rendered in a table of contents.

#### Headings should be nested hierarchically

Beyond the `<h1>`, heading levels should be nested hierarchically to make them easily accessible to users. Think of your heading structure like a nested list:

- `<h1>` Page title
  - `<h2>` Section title
    - `<h3>` Section title
    - `<h3>` Section title
      - `<h4>` Section title
  - `<h2>` Section title

Don't skip heading levels: an `<h4>` should not directly follow an `<h2>`.

In contrast, skipping headline _sizes_ and jumping from e.g. `<Headline size="l" as="h2" />` to `<Headline size="s" as="h4" />` does not constitute an accessibility issue, although we recommend keeping sizes visually consistent across pages.

#### Avoid sections without headings

If a section doesn't have a heading (for example, if it uses a different background color to distinguish it from another section), it will not be easily accessible to blind users.

Consider adding a heading to make the section's purpose clearer.

You can also add visually hidden headings using the [`hideVisually()` style mixin](Features/Style-Mixins/Hide-Visually):

```tsx
import { Headline, hideVisually } from '@sumup-oss/circuit-ui';

function HiddenHeadline() {
  return (
    <Headline as="h2" css={hideVisually}>
      My section
    </Headline>
  );
}
```

#### Avoid headings without sections

Headings typically use large typography, but not all large typography should be a heading.

If you need to render large text that doesn't describe a section, don't use a semantic heading element, and instead use CSS to enlarge the text.

```tsx
import styled from '@emotion/styled';
import { css } from '@emotion/react';

const Price = styled.p(
  ({ theme }) => css`
    font-size: ${theme.typography.headline.one};
    font-weight: bold;
  `,
);

function Product() {
  return (
    <section>
      <Headline as="h2" size="four">
        My product
      </Headline>
      <Price>9,99 €</Price>
      <Body>A description of my product.</Body>
    </section>
  );
}
```

### Resources

#### Testing heading accessibility

Use a tool like [Wave](https://wave.webaim.org/) to extract structure from a page (in Wave, you'll find the page structure under the _Structure_ tab). Verify that sections are appropriately titled and are nested hierarchically.

#### Related WCAG success criteria

- 1.3.1: [Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)
- 2.4.6: [Headings and Labels](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html)
